Skip to content

2. Agents

In one glance

  • You will: Build a small agent and find the reference page for each part of its behavior.
  • You need: The learner runtime installed; model credentials only for optional interactive work.
  • Time: about 8 minutes, orientation.

Part I — Agent development. Work through 2.6. Workshop and consult this chapter when the exercise introduces its subject. Python fundamentals are assumed; no Kubernetes knowledge is needed here.

What will you understand in this chapter?

Start with your small learner_agent, then compare it with the completed AgentOps Agent as you add capabilities.

The reference's composition.py assembles root_agent from a model, instructions, and tools. Its enclosing App registers AgentOpsPolicyPlugin once to govern every model and tool call, including sub-agents and workflow stages.

Deeper: where does this agent go after Chapter 2?

The completed reference already contains the course's capabilities. Chapter 3 explains them, Chapter 4 validates them, Chapters 5 and 6 deploy the application, and Chapter 7 observes it.

Chapter 3 deepens its tools, knowledge, workflows, and delegation; Chapter 8.7 asks you to adapt these boundaries to your own domain.

Begin with First Agent and the Workshop. Consult the other pages when an exercise needs their concepts; the reference development loop requires the larger contributor installation.

  • 2.0. Concepts (concept): The ADK 2.x building blocks — Agent, Runner, Session, Events, Tools, and the graph Workflow.
  • 2.1. First Agent (hands-on): Create a learner-owned agent, check it offline, and optionally inspect a model conversation.
  • 2.2. Models (reference): The optional Ollama contract and the default native Gemini branch.
  • 2.3. Instructions (hands-on): The system instruction, its enforcement map, and a deterministic red/green trajectory contract.
  • 2.4. Sessions (reference): Persistent ADK sessions, A2A tasks (units of work exchanged between agents across process boundaries), lifecycle ownership, and resettable runtime state.
  • 2.5. Dev Loop (hands-on): Offline gates, interactive modes, model-backed evaluations, and failure diagnosis.

You can complete the exercises offline. When model access is available, use a small conversation to compare intended behavior with the events you observe.

Which page owns which part of the agent?

The Agent(...) call in composition.py names each part of the reference agent. Each part is taught by exactly one sub-page, so when a behavior surprises you, there is one page and one module to open.

Concretely, each field of root_agent traces to one owner:

Sub-page What it teaches Owning module / symbol
2.0. Concepts The ADK runtime loop and its object vocabulary google.adk (framework)
2.1. First Agent Composing and running root_agent composition.py (composition root)
2.2. Models Provider selection behind model= model.py build_model, config.py ModelProvider
2.3. Instructions The persona and rules behind instruction= composition.py INSTRUCTION / _instruction
2.4. Sessions Persistent sessions and A2A task state server.py DatabaseSessionService, config.py state_dir
2.5. Dev Loop The offline gates and interactive run modes mise.toml tasks

Tools and policy hooks are named here, not taught here. Owned by Chapter 3 and 4.5. Guardrails.

Deeper: the same map as a diagram, and who owns tools and policy

This diagram maps the anatomy to its owners:

flowchart TD
    concepts["Runtime concepts · 2.0<br/>Agent · Runner · Session · Events"]
    subgraph agent["root_agent — assembled in composition.py · 2.1"]
        model["model = build_model() · 2.2"]
        instr["instruction = _instruction() · 2.3"]
        tools["tools = [reads, actions, memory, skills]<br/>policy plugin on App · Ch. 3 / 4.5"]
    end
    runtime["Persistent runtime · 2.4<br/>DatabaseSessionService · A2A tasks · server.py"]
    loop["Dev loop · 2.5<br/>mise run test · run · web · a2a"]
    concepts --> agent
    agent --> runtime
    loop -. iterates .-> agent

Diagram in words: Runtime concepts lead to one agent assembled from a model, instruction, tools, and an app-level policy plugin; persistent runtime and the dev loop surround it.

The tools= list and app plugin belong to later chapters: 2.1 shows the wiring, Chapter 3 owns each tool, and 4.5. Guardrails owns policy. This page only names the seams.

  • 2.6. Workshop (hands-on): Build eight cumulative Python checkpoints with offline checks and worked solutions.

What proves this chapter worked?

Check your first agent from the repository root without starting a model:

mise run lab -- check 1

Create the step through 2.1. First Agent first. The check proves construction, not model behavior. Continue building your own tools through 2.6. Workshop.

Deeper: how do you validate the completed reference?

After the contributor installation, the full reference suite verifies deterministic behavior and enforces 95% combined line-and-branch coverage:

cd agents/python
mise run test

For a narrower check after a model/config edit, use uv run pytest tests/test_model.py tests/test_config.py. Do not rerun the full suite for every page you read.

2.3. Instructions provides a reference-editing drill. 2.5. Dev Loop owns the full development workflow and its separate model-backed evidence.

You are done when:

  • Your learner-owned step 1 passes its offline check.
  • You can distinguish your cumulative exercise from the completed reference application.
  • You know where to find the model, instruction, session, and development-loop explanations.
  • You can explain what an offline construction check cannot establish about a model's answer.

Continue to 2.1. First Agent to create your learner-owned file, or consult 2.0. Concepts first if the ADK vocabulary is unfamiliar.